docs: expand website documentation with guides and architecture #239
Conversation
- Add installation.md.vm with Maven/Gradle dependencies and snapshots - Add building.md.vm with JDK 17 requirement and CI profile instructions - Add claude-integration.md.vm documenting Claude Code plugin skills - Add 6 guide pages covering OSCAL module loading, data binding, profile resolution, Metapath queries, constraint validation, and architecture - Update site.xml with Documentation and Guides navigation menus - Enhance index.md.vm with quick start and feature overview
📝 WalkthroughWalkthroughThis PR adds extensive documentation and site content (installation, building, architecture, guides for binding context, reading/writing, profile resolution, Metapath execution, and constraint validation), updates site navigation and CSS, and bumps the minimum Maven requirement in README from 3.8.4 to 3.9.0. No public API or runtime code changes. Changes
Sequence Diagram(s)(omitted — changes are documentation and site navigation only) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @src/site/markdown/guides/resolving-profiles.md.vm:
- Around line 30-48: The example uses ProfileResolver.resolve(Profile) and
assumes it returns a Catalog, but the real API is ProfileResolver.resolve(...)
which accepts a URL/File/Path/IDocumentNodeItem/IRootAssemblyNodeItem and
returns an IDocumentNodeItem; change the sample to call resolver.resolve with a
Path/File/URL (e.g., Path.of("profile.json")) to obtain an IDocumentNodeItem,
then extract the Catalog from that IDocumentNodeItem if needed; update
references in the snippet from Profile and Catalog to use the deserializer only
for reading if you choose to build an IDocumentNodeItem manually, or drop
deserializer and pass Path/File directly to ProfileResolver.resolve.
- Around line 54-65: The example using DefaultBoundLoader should clarify that
the variable context must be an OscalBindingContext instance; update the snippet
or surrounding text to create or reference an OscalBindingContext (e.g.,
OscalBindingContext.instance()) before calling new DefaultBoundLoader(context).
Ensure the instructions mention DefaultBoundLoader, IDocumentLoader,
ProfileResolver, resolver.setDocumentLoader(...), and resolver.resolve(...) so
readers know to pass the OscalBindingContext into DefaultBoundLoader rather than
a generic object.
In @src/site/markdown/index.md.vm:
- Around line 46-62: The Quick Start example uses a nonexistent
OscalBindingContext.newDeserializer() API; replace that usage with the supported
APIs: either call
OscalBindingContext.instance().loadCatalog(Path.of("catalog.json")) to load a
Catalog directly, or obtain a loader via
OscalBindingContext.instance().newBoundLoader() and then call
loader.load(Catalog.class, Path.of("catalog.json")); update the imports and
remove the IDeserializer usage accordingly.
🧹 Nitpick comments (5)
src/site/markdown/guides/executing-metapath.md.vm (2)
37-39: Add null safety check for result processing.When processing Metapath results, not all items may be convertible to atomic values. Consider adding a check before calling
toAtomicItem().asString()to handle cases where the item might not be atomic.♻️ Suggested improvement for safer result processing
// Process results for (IItem item : results) { - System.out.println("Found: " + item.toAtomicItem().asString()); + if (item instanceof IAtomicItem) { + System.out.println("Found: " + ((IAtomicItem) item).asString()); + } else { + System.out.println("Found: " + item); + } }
1-273: Consider adding import statement for missing type in example.Line 38's example references
IAtomicItem(if the suggested refactor is applied), but the imports section (lines 11-20) doesn't include it. Consider adding the import for completeness.Add missing import for completeness
import dev.metaschema.core.metapath.MetapathExpression; import dev.metaschema.core.metapath.IMetapathExpression; import dev.metaschema.core.metapath.item.IItem; +import dev.metaschema.core.metapath.item.IAtomicItem; import dev.metaschema.core.metapath.item.ISequence;src/site/markdown/guides/reading-writing-data.md.vm (1)
161-161: The code likely handles the extension correctly as-is.The
getDefaultExtension()method from the MetaschemaFormatenum conventionally returns the file extension including the leading dot (e.g.,".json",".xml",".yaml"), which aligns with standard Java API conventions for file extension methods. The regex\\.[^.]+$correctly matches and replaces the existing extension with this value. No changes needed.src/site/markdown/guides/validating-with-constraints.md.vm (1)
103-114: Avoid usingordinal()for enum comparisons.The code uses
finding.getSeverity().ordinal() >= Severity.ERROR.ordinal()to compare severity levels. Usingordinal()is fragile because:
- If enum order changes, the comparison breaks
- It doesn't express intent clearly
♻️ Proposed refactor using safer comparison
Consider using enum comparison methods or explicit severity checks:
@Override public void handleFinding(IFinding finding) { findings.add(finding); // Log immediately - if (finding.getSeverity().ordinal() >= Severity.ERROR.ordinal()) { + if (finding.getSeverity().compareTo(Severity.ERROR) >= 0) { System.err.println("Validation error: " + finding.getMessage()); } } public boolean hasErrors() { return findings.stream() - .anyMatch(f -> f.getSeverity().ordinal() >= Severity.ERROR.ordinal()); + .anyMatch(f -> f.getSeverity().compareTo(Severity.ERROR) >= 0); }Alternatively, if the Severity enum provides level comparison methods, use those for clearer intent.
src/site/site.xml (1)
58-71: Consider removing duplicate Architecture link.The "Architecture" item appears in both the Documentation menu (line 62) and the Guides menu (line 70), both pointing to the same
guides/architecture.htmlfile. This duplication may confuse users about where to find architectural documentation.Consider whether Architecture belongs primarily in Documentation (as a high-level overview) or in Guides (as a usage-oriented guide), and remove it from the other menu.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
README.mdsrc/site/markdown/building.md.vmsrc/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/architecture.md.vmsrc/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/guides/loading-oscal-modules.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/guides/resolving-profiles.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/index.md.vmsrc/site/markdown/installation.md.vmsrc/site/resources/css/custom.csssrc/site/site.xml
🧰 Additional context used
🧠 Learnings (13)
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/claude-integration.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vmsrc/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/building.md.vmsrc/site/markdown/installation.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examples
Applied to files:
src/site/markdown/guides/validating-with-constraints.md.vm
📚 Learning: 2025-12-30T04:19:49.192Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Applied to files:
src/site/markdown/guides/validating-with-constraints.md.vm
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/guides/validating-with-constraints.md.vm
📚 Learning: 2025-12-24T21:22:07.082Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:22:07.082Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
src/site/markdown/guides/validating-with-constraints.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. Use the XPath 3.1 specification (https://www.w3.org/TR/xpath-31/) and XPath Functions 3.1 (https://www.w3.org/TR/xpath-functions-31/) as authoritative reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to core/src/main/antlr4/** : Metapath parser is generated from ANTLR4 grammar files in core/src/main/antlr4. Code generation occurs during Maven build producing output in target/generated-sources/
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-01-07T00:50:46.218Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/type/InstanceOf.java:87-88
Timestamp: 2025-01-07T00:50:46.218Z
Learning: In the Metapath implementation, child expressions should be called using `accept()` rather than `evaluate()` to ensure proper management of the execution stack through push/pop operations. The `evaluate()` method is an internal implementation detail that performs the actual evaluation.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-01-07T00:51:17.257Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySequenceConstructor.java:63-63
Timestamp: 2025-01-07T00:51:17.257Z
Learning: In the Metapath implementation, expression evaluation must go through the `accept()` method rather than calling `evaluate()` directly, as `accept()` handles the push/pop operations on the execution stack which is used for debugging and error reporting.
Applied to files:
src/site/markdown/guides/executing-metapath.md.vm
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : All code changes must follow the Javadoc style guide (docs/javadoc-style-guide.md). New code requires 100% Javadoc coverage on public/protected members. Modified code must add/update Javadoc on any members touched. All Javadoc must include param, return, throws tags in the correct order (BLOCKING)
Applied to files:
src/site/markdown/building.md.vm
📚 Learning: 2025-12-13T15:29:03.112Z
Learnt from: david-waltermire
Repo: metaschema-framework/liboscal-java PR: 222
File: .github/workflows/build.yml:30-32
Timestamp: 2025-12-13T15:29:03.112Z
Learning: In the liboscal-java repository, nightly builds are managed independently using GitHub Actions schedule triggers (cron), not via repository_dispatch from metaschema-java. Each repo in the metaschema-framework manages its own nightly builds.
Applied to files:
src/site/markdown/building.md.vm
📚 Learning: 2025-12-30T19:08:21.896Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:08:37.155Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Applied to files:
src/site/markdown/index.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (18)
src/site/resources/css/custom.css (1)
24-29: LGTM! CSS fix appropriately addresses the flexmark limitation.The CSS override correctly targets table headers with sufficient specificity to override Bootstrap's default styles. The use of
!importantis justified here, and the comment clearly explains the rationale.src/site/markdown/guides/executing-metapath.md.vm (1)
215-232: LGTM! Well-designed caching utility.The
MetapathQueryCacheimplementation correctly usesConcurrentHashMapandcomputeIfAbsentfor thread-safe caching of compiled Metapath expressions. This is a solid pattern for improving query performance.src/site/markdown/guides/reading-writing-data.md.vm (2)
145-173: Batch conversion example is well-structured with proper error handling.The batch conversion method correctly:
- Uses try-with-resources for the file stream
- Filters by format using
Format.valueOf(p)- Handles file extension replacement with a proper regex
- Converts IOException to UncheckedIOException for lambda usage
218-230: Good error handling documentation.The error handling example properly demonstrates catching both
DeserializationException(for parsing errors) andIOException(for I/O errors), with appropriate user-friendly error messages.src/site/markdown/guides/architecture.md.vm (3)
234-250: Threading model guidance is clear and correct.The threading model section accurately describes that:
- The binding context singleton is thread-safe for reads
- Deserializers and serializers should be created per-operation
- Model objects are not thread-safe for concurrent modification
The code example demonstrates the correct pattern for parallel processing.
254-259: Helpful memory considerations for production use.The memory considerations section provides valuable guidance about:
- Large catalogs consuming significant memory
- Profile resolution loading entire import chains
- Considering streaming for large documents
This is practical operational advice that will help users avoid common pitfalls.
19-35: The OSCAL Metaschema module list is complete and accurate.The diagram correctly shows all eight main OSCAL document types: Catalog, Profile, MappingCollection (included as
oscal_mapping), SSP, Component Definition, Assessment Plan, Assessment Results, and PoA&M. MappingCollection is already documented in the Package Structure section (line 47). The common/shared modules (metadata, mapping-common, control-common) are foundational dependencies rather than primary document types, so their omission from this dependency hierarchy is appropriate.README.md (1)
32-32: The Maven 3.9.0 requirement is properly documented and justified.The version bump is consistently documented in both README.md and building.md.vm (the source template). Maven 3.9.0 introduced HTTP blocking for repositories (enforcing HTTPS), a security feature that warrants the upgrade. No changes needed.
src/site/markdown/claude-integration.md.vm (1)
1-139: Excellent Claude Code integration documentation.This guide provides clear, practical information about using Claude Code with the project. The structure is logical, covering:
- Purpose and capabilities
- Available plugins with skill descriptions
- Installation instructions
- Example workflows for different use cases
- Integration with project development practices
The reference to CLAUDE.md as the canonical coding guidelines document aligns with project conventions.
src/site/markdown/guides/loading-oscal-modules.md.vm (2)
1-228: Comprehensive and well-structured binding context guide.This documentation provides excellent coverage of
OscalBindingContextusage, including:
- Clear explanation of the binding context's purpose
- Singleton pattern with rationale
- Complete document type coverage
- Helpful model mapping section showing OSCAL structure
- Practical code examples for common operations
- Important thread safety guarantees
- Best practices
The Model Mapping section (lines 81-150) is particularly valuable for developers learning to navigate the API.
73-73: Verify MappingCollection document type.
MappingCollectionis listed as an OSCAL document type. This should be verified to be part of the OSCAL specification (same concern as in index.md.vm).This verification was already requested in the index.md.vm review. The same confirmation applies here.
src/site/markdown/index.md.vm (2)
129-129: Line 129 is blank; this review comment references a non-existent issue.The actual references to documentation URLs in
src/site/markdown/index.md.vmappear at lines 29 and 116, not line 129. Those lines correctly referencehttps://metaschema-java.metaschema.dev/, which is the appropriate project-specific documentation URL for the Metaschema Java Tools. This follows the established pattern used in the project (e.g.,https://liboscal-java.metaschema.dev/for this library's docs). The URL is consistent across the codebase and does not require changes.Likely an incorrect or invalid review comment.
95-95: No changes needed — MappingCollection is confirmed as a valid OSCAL document type.
MappingCollectionis the official root document type for the OSCAL Control Mapping model in OSCAL 1.0, documented in the NIST OSCAL XML and JSON format references. The reference in the documentation is accurate.src/site/markdown/guides/validating-with-constraints.md.vm (1)
20-36: Verify constraint validation API methods - documentation may not match implementation.The
setConstraintValidationEnabled(true)method is not found in the codebase. Actual constraint validation in tests uses different patterns:
bindingContext.validateWithConstraints(...)for constraint-specific validationDeserializationFeature.DESERIALIZE_VALIDATE_CONSTRAINTSwithdisableFeature()to control validation during deserializationcontext.validate(catalog)returnsIValidationResultwithisPassing()andgetFindings()methodsThe documented deserializer-based approach may come from an external metaschema-framework dependency, but the working example code in
OscalValidationTest.javashows constraint validation handled differently via binding context methods rather than deserializer configuration.src/site/markdown/installation.md.vm (2)
139-163: LGTM! Verification example is clear and practical.The verification code demonstrates loading an OSCAL catalog from the official NIST repository, providing users with a realistic test of their installation. The code correctly uses the
dev.metaschema.oscal.libpackage structure.
22-22: No changes needed. The Maven 3.9.0 minimum version specified in installation.md.vm is accurate and consistent with the README.md, which explicitly states: "This project can be built with Apache Maven version 3.9.0 or greater."src/site/markdown/building.md.vm (2)
7-11: Consistent Maven version requirement.The Maven 3.9.0 minimum version matches the requirement documented in
installation.md.vm, ensuring consistency across the documentation.
161-167: Remove or revise the claim that install and site goals must run together in a single invocation.The build configuration shows no evidence supporting this requirement. The javadoc plugin is not explicitly configured (uses Maven defaults), and generated sources are integrated into the normal build process as part of the compile phase. Once
mvn installcompletes successfully, the generated OSCAL model classes are available in the local repository and on disk. Standard Maven behavior allowsmvn siteto run independently afterward without requiring a combined invocation.If you have encountered Javadoc failures when running
mvn siteindependently, that suggests a configuration issue rather than a fundamental requirement. Consider investigating whether the issue can be resolved by ensuring generated sources are properly accessible to the site build.Likely an incorrect or invalid review comment.
- Fix Quick Start example to use loadCatalog convenience method - Fix ProfileResolver API to use Path and return IDocumentNodeItem
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
src/site/markdown/guides/resolving-profiles.md.vm (1)
241-244: Clarify circular import handling in best practices.Line 244 mentions "Check for circular imports - Can cause infinite loops" but doesn't explain whether the ProfileResolver library automatically detects and prevents circular imports, or if users must implement their own detection logic.
Please add clarification:
- Does ProfileResolver throw an exception when circular imports are detected?
- If not, how should users implement this best practice?
- Are there specific error messages or exceptions to watch for?
📝 Suggested enhancement to the documentation
Add a sentence explaining the library's behavior:
4. **Check for circular imports** - Can cause infinite loops + - The ProfileResolver detects circular imports and throws ProfileResolutionException [OR: Users should track import chains manually to avoid circular references]
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/site/markdown/guides/resolving-profiles.md.vmsrc/site/markdown/index.md.vm
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-12-30T04:19:49.192Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java:480-484
Timestamp: 2025-12-30T04:19:49.192Z
Learning: In metaschema-framework/metaschema-java, when users configure custom superinterfaces via binding configuration, david-waltermire prefers both documentation (explaining how to add dependencies to the Maven plugin) and validation mechanisms (warnings when classes aren't on classpath) to prevent redundant IBoundObject interface additions during code generation.
Applied to files:
src/site/markdown/guides/resolving-profiles.md.vmsrc/site/markdown/index.md.vm
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-24T21:21:40.208Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:40.208Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2025-12-30T19:08:21.896Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 605
File: src/site/markdown/index.md.vm:3-3
Timestamp: 2025-12-30T19:08:21.896Z
Learning: In the metaschema-framework/metaschema-java repository, https://framework.metaschema.dev/ is the project's preferred and canonical documentation URL for the Metaschema framework. While https://pages.nist.gov/metaschema/ is an alternative, the project uses framework.metaschema.dev as the official reference in documentation and should not be changed to pages.nist.gov URLs.
Applied to files:
src/site/markdown/index.md.vm
📚 Learning: 2026-01-05T16:08:37.155Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java-templates/dev/metaschema/core/MetaschemaJavaVersion.java:2-2
Timestamp: 2026-01-05T16:08:37.155Z
Learning: In metaschema-framework/metaschema-java, the canonical Java package naming convention is dev.metaschema.* (renamed from gov.nist.secauto.metaschema.* as of PR #618).
Applied to files:
src/site/markdown/index.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (5)
src/site/markdown/guides/resolving-profiles.md.vm (2)
1-252: Documentation is comprehensive and well-structured.This guide provides excellent coverage of profile resolution concepts, use cases, and implementation patterns. The examples progress logically from basic usage to advanced scenarios, and the explanations are clear and developer-friendly. The inclusion of error handling, best practices, and next steps makes this a valuable resource.
29-44: Update documentation to use correct ProfileResolver method names.The ProfileResolver API uses
resolveProfile()method names (notresolve()). The correct signatures are:
resolveProfile(Path)→IDocumentNodeItemresolveProfile(URL)→IDocumentNodeItemresolveProfile(File)→IDocumentNodeItemUpdate the code examples to reflect the actual method names and ensure the cast to
Catalogis included, since all methods returnIDocumentNodeItem.Likely an incorrect or invalid review comment.
src/site/markdown/index.md.vm (3)
43-58: Quick Start example correctly updated.The Quick Start section now uses the
loadCatalogconvenience method as intended per the PR objectives. The example is clear, concise, and demonstrates the proper usage pattern for loading and accessing OSCAL content.
83-97: Document types table correctly includes MappingCollection.The Supported OSCAL Document Types table now includes the MappingCollection document type as specified in the PR objectives. The table is well-organized, consistent, and provides clear descriptions for each OSCAL document type.
1-135: Excellent documentation expansion and restructuring.The homepage has been significantly enhanced with:
- Clear value proposition explaining why developers should use this library
- Comprehensive feature descriptions that help users understand capabilities
- Well-organized navigation with logical progression from introduction to advanced topics
- Complete guide links connecting users to detailed documentation
- Ecosystem context showing related projects and tools
The structure follows documentation best practices with progressive disclosure and clear calls-to-action. The additions significantly improve the user experience for developers discovering and learning the library.
aj-stein
left a comment
aj-stein
left a comment
There was a problem hiding this comment.
Very cool, I would have benefitted from this like the AI, albeit much slower, a few years ago. These references are very clear and helpful.
- validating-with-constraints.md.vm: Fixed incorrect API examples - Replaced non-existent setConstraintValidationEnabled with correct API - Updated to use IBoundLoader.enableFeature() and validateWithConstraints() - Replaced custom handler example with FindingCollectingConstraintValidationHandler - reading-writing-data.md.vm: Added missing imports - Added Stream, Files, Path, IOException, UncheckedIOException imports - executing-metapath.md.vm: Added missing imports - Added Map, ConcurrentHashMap imports to MetapathQueryCache example
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @src/site/markdown/guides/reading-writing-data.md.vm:
- Around line 55-62: The code sample is missing the java.net.URL import used by
URI.toURL(); add an import for java.net.URL alongside the existing import
java.net.URI so the usage of URI.create(...).toURL() compiles; locate the block
containing IDeserializer<Catalog> deserializer = context.newDeserializer(...)
and Catalog catalog =
deserializer.deserialize(URI.create("https://example.com/catalog.json").toURL())
and add the import statement for java.net.URL.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
src/site/markdown/guides/executing-metapath.md.vmsrc/site/markdown/guides/reading-writing-data.md.vmsrc/site/markdown/guides/validating-with-constraints.md.vm
🚧 Files skipped from review as they are similar to previous changes (2)
- src/site/markdown/guides/executing-metapath.md.vm
- src/site/markdown/guides/validating-with-constraints.md.vm
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2026-01-05T18:03:33.537Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 618
File: core/src/main/java/dev/metaschema/core/datatype/package-info.java:52-52
Timestamp: 2026-01-05T18:03:33.537Z
Learning: In metaschema-framework/metaschema-java, CLAUDE.md is the canonical coding-guidelines document and now specifies dev.metaschema.* as the Java package convention (updated in PR #618).
Applied to files:
src/site/markdown/guides/reading-writing-data.md.vm
📚 Learning: 2024-12-12T00:15:45.005Z
Learnt from: aj-stein-gsa
Repo: metaschema-framework/oscal-server PR: 44
File: .oscal/component.oscal.yaml:2-2
Timestamp: 2024-12-12T00:15:45.005Z
Learning: When reviewing OSCAL content in YAML format, validate general content quality aspects like UUID uniqueness across entities, in addition to OSCAL-specific validations.
Applied to files:
src/site/markdown/guides/reading-writing-data.md.vm
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (9)
src/site/markdown/guides/reading-writing-data.md.vm (9)
29-51: LGTM! Clear example of format-agnostic deserialization.The code example effectively demonstrates reading OSCAL documents in all three supported formats using the same API pattern.
66-75: Good use of try-with-resources for stream management.The example correctly demonstrates resource handling and provides URI context for the InputStream-based deserialization.
93-112: LGTM! Serialization examples follow best practices.Both examples demonstrate proper resource management with try-with-resources and include all necessary imports.
116-124: Clear demonstration of serializing to a string.The example correctly uses
StringWriterfor in-memory serialization.
185-220: Good coverage of different OSCAL document types.The examples effectively demonstrate that the same serialization patterns apply across all OSCAL document types, with appropriate type-specific property access.
224-236: Proper exception handling pattern demonstrated.The example correctly distinguishes between deserialization errors and I/O errors, providing appropriate error handling guidance.
238-252: Well-structured best practices and navigation.The best practices section reinforces the patterns demonstrated in the code examples, and the next steps provide clear pathways to related functionality.
144-179: The batch conversion example is well-structured with proper resource management and exception handling. TheFormat.getDefaultExtension()method is correctly used and is available as an instance method on the Format enum from the metaschema-databind library.
81-87: Remove or correct theFormat.valueOf(Path)example — this API does not exist.The Metaschema databind library uses
IBoundLoader(obtained viacontext.newBoundLoader()) for automatic format detection, notFormat.valueOf(Path). TheFormatclass is an enum with static constants (Format.JSON,Format.YAML,Format.XML), and its inheritedvalueOf()method accepts a String parameter only. To auto-detect format from a file, useIBoundLoader.load(Path)which internally usesFormatDetector.detect(InputStream)to sniff the content.Likely an incorrect or invalid review comment.
david-waltermire
merged commit a01be7b
into
metaschema-framework:develop
2 participants
Summary
Test plan
mvn install site -DskipTestsbuilds without errorsSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.